Hermes Agent 学习手册

版本： v2.0（基于 Hermes Agent v0.12.0，2026.4.30）
更新日期： 2026-05-08
说明： 本文档完全基于 v0.12.0 实际命令重写，移除了所有 OpenClaw 残留命令。

第一章：基础入门

1.1 概述

Hermes Agent 是由 Nous Research 开发的 AI 助手框架，运行在终端、消息平台和 IDE 中。与 Claude Code（Anthropic）、Codex（OpenAI）、OpenClaw 属于同一类别——通过工具调用与系统交互的自主编码 Agent。

核心特点：

自我进化：通过 Skills 持久化可复用流程，积累经验
跨会话记忆：记住用户偏好、环境细节和经验教训
多平台网关：同一 Agent 同时接入 Telegram、Discord、Slack、WhatsApp、企业微信、飞书等
Provider 无关：任意切换模型提供商，配置不变
多 Profile：运行多个独立配置的 Hermes 实例
可扩展：插件、MCP 服务器、自定义工具、 Cron 调度

1.2 安装与启动

# 安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 验证版本
hermes version
# 输出：Hermes Agent v0.12.0 (2026.4.30)

# 交互式对话
hermes

# 单次查询（oneshot）
hermes chat -q "用 Python 写一个快速排序"

# 配置向导
hermes setup

# 健康检查
hermes doctor

1.3 核心概念

概念	说明
Provider	模型供给方（minimax-cn、deepseek、openai 等）
Toolset	工具集（web、terminal、file、vision 等）
Skill	可发布的技能模块（.md 格式，含工作流程）
Profile	独立配置的 Hermes 实例
Gateway	消息网关，接入各 IM 平台
Session	会话历史，持久化在 SQLite

第二章：CLI 命令详解

2.1 全局选项

hermes [flags] [command]

  --version, -V          输出版本号
  -z, --oneshot TEXT     单次查询模式（无 Banner，无工具预览）
  -m, --model MODEL      本次调用使用的模型（如 MiniMax-M2.7-highspeed）
  --provider PROVIDER     本次调用使用的 Provider
  -t, --toolsets LIST    本次启用的工具集
  -r, --resume SESSION   恢复指定会话
  -c, --continue [NAME]  恢复最近会话或指定名称的会话
  -w, --worktree        隔离 git worktree 模式（并行 Agent）
  -s, --skills SKILLS   预加载技能（逗号分隔或重复 flag）
  --profile NAME         使用指定 Profile
  --yolo                 跳过所有危险命令确认
  --tui                 启动现代 TUI（替代经典 REPL）

2.2 子命令一览

hermes chat               交互式对话（默认）
hermes model              交互式选择默认模型和 Provider
hermes fallback           管理备用 Provider（主 Provider 失败时启用）
hermes setup              配置向导（可选：model/tts/terminal/gateway/tools/agent）
hermes config             管理配置（show/edit/set/path/env-path/check/migrate）
hermes auth               管理凭证池（add/list/remove/reset）
hermes login/logout       OAuth 登录/登出
hermes tools              管理工具集（list/disable/enable）
hermes skills             管理技能（browse/search/install/inspect/list/check/update/audit/uninstall/reset/publish/snapshot/tap/config）
hermes mcp                管理 MCP 服务器（serve/add/remove/list/test/configure）
hermes gateway            消息网关（run/start/stop/restart/status/install/uninstall/setup）
hermes cron               定时任务（list/create/pause/resume/run/remove/status/tick）
hermes webhook            Webhook 管理（subscribe/list/remove/test）
hermes kanban             多人协作看板
hermes hooks              Shell 钩子管理
hermes sessions           会话管理（list/export/delete/prune/stats/rename/browse）
hermes profile            Profile 管理（list/use/create/delete/show/alias/rename/export/import）
hermes plugins            插件管理
hermes doctor             环境诊断
hermes dump               导出调试信息
hermes debug              上传调试报告
hermes backup             备份 Hermes 目录
hermes import             从备份恢复
hermes version            版本信息
hermes update             更新到最新版本
hermes acp                以 ACP 协议服务器运行
hermes logs               查看日志（--follow 实时）
hermes dashboard          启动 Web UI 面板
hermes claw               OpenClaw 迁移工具
hermes pairing            管理 DM 配对码
hermes insights           使用统计
hermes completion         生成 Shell 补全脚本

2.3 重要命令详解

`hermes chat`（交互式对话）

hermes chat [flags]
  -q, --query TEXT        单次查询（非交互）
  -m, --model MODEL       本次模型
  --provider PROVIDER     本次 Provider
  -t, --toolsets LIST    工具集
  -Q, --quiet            静默模式（无 Banner 和工具预览）
  --checkpoints          启用文件系统快照（/rollback 可回滚）
  --source TAG            会话来源标签（默认: cli）

`hermes model`（模型选择）

hermes model              # 交互式选择器

⚠️ 这是顶层 CLI 命令，不是斜杠命令。交互式选择 MiniMax Provider + 模型。

`hermes config`

hermes config show                # 显示当前配置
hermes config edit                # 在 $EDITOR 中编辑
hermes config set KEY VAL         # 设置配置值
hermes config path                # 打印配置文件路径
hermes config env-path            # 打印 .env 文件路径
hermes config check               # 检查配置完整性
hermes config migrate             # 更新到新版配置格式

`hermes skills`

hermes skills browse              # 浏览所有可用技能
hermes skills search <keyword>    # 搜索技能
hermes skills install <id>        # 安装技能
hermes skills inspect <id>        # 预览技能（不安装）
hermes skills list                # 列出已安装技能
hermes skills check               # 检查更新
hermes skills update              # 更新已安装技能
hermes skills audit               # 重新扫描已安装技能
hermes skills uninstall <name>    # 卸载技能
hermes skills reset <name>       # 重置内置技能
hermes skills publish <path>     # 发布技能
hermes skills snapshot           # 导出/导入技能配置
hermes skills tap add <repo>     # 添加技能源
hermes skills config             # 交互式配置（启用/禁用）

`hermes gateway`

hermes gateway run                # 前台运行（WSL/Docker 推荐）
hermes gateway start              # 启动 systemd 后台服务
hermes gateway stop               # 停止服务
hermes gateway restart            # 重启服务
hermes gateway status            # 查看服务状态
hermes gateway install           # 安装为后台服务
hermes gateway uninstall         # 卸载服务
hermes gateway setup             # 配置消息平台

`hermes cron`

hermes cron list                 # 列出定时任务
hermes cron create <schedule>   # 创建任务（如 '30m'、'0 9 * * *'）
hermes cron edit <id>           # 编辑任务
hermes cron pause <id>          # 暂停任务
hermes cron resume <id>         # 恢复任务
hermes cron run <id>            # 立即执行一次
hermes cron remove <id>         # 删除任务
hermes cron status             # 检查调度器状态

⚠️ Cron 会话中 send_message 工具通常不可用，需用 Python 直接调用。

`hermes sessions`

hermes sessions list             # 列出最近会话
hermes sessions browse          # 交互式选择器
hermes sessions rename <id> <title>  # 重命名会话
hermes sessions delete <id>     # 删除指定会话
hermes sessions prune           # 清理旧会话
hermes sessions export <file>  # 导出为 JSONL
hermes sessions stats           # 显示存储统计

`hermes mcp`

hermes mcp serve                # 将 Hermes 作为 MCP 服务器运行
hermes mcp add <name>           # 添加 MCP 服务器
hermes mcp remove <name>        # 移除 MCP 服务器
hermes mcp list                # 列出已配置服务器
hermes mcp test <name>         # 测试连接
hermes mcp configure <name>    # 切换工具选择

2.4 Provider 切换的正确方式

跨 Provider 切换时，必须清除残留的 base_url：

# 切换到 MiniMax
hermes model
# 或
hermes config set model.provider minimax-cn
hermes config set model.base_url ''   # 清除旧地址，使用 Provider 默认端点

# 切换到 DeepSeek
hermes config set model.provider deepseek
hermes config set model.default deepseek-v4-flash
hermes config set model.base_url ''

Provider 默认端点：

Provider	默认 Base URL
`minimax-cn`	`https://api.minimaxi.com/anthropic`
`minimax`	`https://api.minimaxi.com/v1`
`deepseek`	`https://api.deepseek.com/v1`
`openai`	`https://api.openai.com/v1`
`anthropic`	`https://api.anthropic.com`

第三章：斜杠命令详解

在 hermes chat 交互模式中输入 / 开头的命令。所有斜杠命令均定义在 hermes_cli/commands.py 的 COMMAND_REGISTRY 中。

3.1 会话控制

命令	说明
`/new`（别名 `/reset`）	新建会话（新的 Session ID）
`/clear`	清屏并新建会话（仅 CLI）
`/redraw`	强制重绘 UI（修复终端漂移，仅 CLI）
`/stop`	终止所有后台进程
`/branch`（别名 `/fork`）	分支当前会话（探索不同路径）
`/rollback`	列出或恢复文件系统快照
`/snapshot`（别名 `/snap`）	创建/恢复 Hermes 配置状态快照
`/background`（别名 `/bg`, `/btw`）	在后台运行提示
`/queue`（别名 `/q`）	队列下一轮输入（不中断当前）
`/steer`	在下次工具调用后注入消息（不中断）
`/compress`	手动压缩对话上下文
`/title`	设置会话标题

3.2 信息查询

命令	说明
`/help`	显示可用命令
`/commands`	分页浏览所有命令和技能
`/status`	显示当前会话信息
`/profile`	显示当前激活的 Profile 名称
`/config`	显示当前配置
`/usage`	显示 Token 消耗和限速信息
`/insights`	显示使用分析
`/platforms`	显示消息平台连接状态
`/gquota`	显示 Google Gemini Code Assist 配额
`/agents`（别名 `/tasks`）	显示活跃 Agent 和运行中任务

3.3 配置调整

命令	说明
`/model <name>`	切换当前会话的模型
`/personality <name>`	设置预定义人格（kawaii/terse/assistant 等）
`/reasoning`	管理推理 effort 和显示
`/fast`	切换快速模式（OpenAI Priority / Anthropic Fast）
`/skin`	显示或切换显示主题
`/indicator`	切换 TUI 忙碌指示器样式
`/voice`	切换语音模式
`/busy`	控制忙碌时 Enter 键行为（interrupt/queue/ignore）
`/verbose`	循环切换：off → new → all → verbose
`/footer`	切换最终回复的网关运行时元数据页脚
`/yolo`	切换 YOLO 模式（跳过危险命令确认）
`/config`	显示当前配置
`/statusbar`	切换上下文/模型状态栏（仅 CLI）

3.4 工具与技能

命令	说明
`/tools`	管理工具（`/tools [list\\|disable\\|enable] [name...]`）
`/toolsets`	列出可用工具集
`/skills`	搜索、安装、管理技能
`/cron`	管理定时任务
`/curator`	后台技能维护（状态/运行/固定/归档）
`/kanban`	多人协作看板
`/reload`	重新加载 .env 变量到当前会话
`/reload-mcp`	重新加载 MCP 服务器配置
`/reload-skills`	重新扫描 ~/.hermes/skills/
`/browser`	连接浏览器工具到 CDP
`/plugins`	列出已安装插件

3.5 平台与网关

命令	说明
`/platforms`	显示消息平台状态
`/restart`	排空活跃任务后优雅重启网关
`/sethome`	将当前聊天设为主页频道
`/approve`	批准待处理危险命令
`/deny`	拒绝待处理危险命令

3.6 其他

命令	说明
`/update`	更新到最新版本
`/debug`	上传调试报告并获取分享链接
`/copy`	复制最后一条助手回复到剪贴板
`/paste`	粘贴剪贴板图片
`/image`	为下一条提示附加本地图片
`/quit`（别名 `/exit`）	退出 CLI

3.7 实际不存在的斜杠命令（OpenClaw 残留）

以下斜杠命令在 Hermes v0.12.0 中不存在：

/provider        ❌ 不存在
/temp           ❌ 不存在
/max_tokens     ❌ 不存在
/system         ❌ 不存在
/undo           ❌ 不存在
/retry <n>      ❌ 不存在（仅 /retry，无参数）
/goto           ❌ 不存在
/search         ❌ 不存在
/context        ❌ 不存在
/tool           ❌ 不存在
/tooloff        ❌ 不存在
/toolon         ❌ 不存在
/profile list   ❌ 不存在
/profile info   ❌ 不存在
/prompt         ❌ 不存在
/attach         ❌ 不存在（用 /image 或 /paste）
/export         ❌ 不存在
/read           ❌ 不存在

第四章：配置体系

4.1 配置文件

~/.hermes/config.yaml — 主配置
~/.hermes/.env — API Key 和密钥
~/.hermes/profiles/<name>/ — Profile 隔离配置
~/.hermes/sessions/ — 会话历史（SQLite）
~/.hermes/skills/ — 安装的技能
~/.hermes/memories/ — 跨会话记忆
~/.hermes/logs/ — 日志文件

4.2 config.yaml 顶级字段一览

model                 主模型配置（default/provider/base_url/name）
providers            Provider 全局配置
fallback_providers    备用 Provider 列表
credential_pool_strategies  多 Key 时如何轮换
toolsets              全局默认工具集
agent                 Agent 行为控制（max_turns/gateway_timeout 等）
terminal              终端执行环境（backend/timeout/docker 等）
browser               浏览器自动化配置
checkpoints           文件系统快照
file_read_max_chars   单次文件读取上限
tool_output           工具输出截断
tool_loop_guardrails  工具循环防护
compression           上下文压缩
prompt_caching        Prompt 缓存
bedrock               AWS Bedrock 配置
auxiliary             辅助模型配置（vision/compression/session_search 等）
display               界面显示控制（personality/streaming/skin 等）
dashboard             Web Dashboard
privacy               隐私控制
tts                   文字转语音
stt                   语音转文字
voice                 语音交互控制
human_delay           人工延迟模拟
context               上下文引擎
memory                记忆配置
delegation            子 Agent 配置
prefill_messages_file 预填充消息文件
goals                 目标配置
skills                技能配置
curator               后台技能维护
honcho                Honcho 记忆集成
timezone              时区
discord/telegram/slack/whatsapp/mattermost  各平台配置
approvals             审批配置
command_allowlist     命令白名单
quick_commands        快捷命令
hooks                 Shell 钩子
hooks_auto_accept     自动接受钩子
personalities         自定义人格
security              安全配置（网站黑名单/PII 脱敏等）
cron                  Cron 配置
kanban                看板配置
code_execution        代码执行配置
logging               日志配置
model_catalog         模型目录
network               网络配置
sessions              会话存储配置
onboarding            引导配置
updates               更新配置
smart_model_routing   智能模型路由
platforms             各平台配置（wecom 等）
mcp_servers           MCP 服务器配置
session_reset         会话重置配置
plugins               插件配置
fallback_model        备用模型
<provider-name>       各 Provider 的凭证（如 minimax-cn）

第五章：Skills 技能系统

5.1 技能结构

技能是 .md 文件，位于 ~/.hermes/skills/ 或技能注册表目录中：

~/.hermes/skills/
├── api/
│   └── minimax-api/
│       └── SKILL.md          # 技能定义文件
├── productivity/
│   └── obsidian/
│       └── SKILL.md

5.2 技能元数据（SKILL.md 开头）

name: skill-name
description: 技能描述
version: 1.0.0
author: 作者
tags: [tag1, tag2]
related_skills: [other-skill]

5.3 加载与使用

# CLI 中预加载
hermes -s minimax-api,github-auth

# 交互模式中加载
/hermes skills
马秘书: /skill <名称>

# 会话中搜索
/hermes skills search douyin

5.4 技能触发条件

技能文件 body 中的 ## Trigger 或条件描述决定何时加载：

## Trigger
当用户询问 GitHub 相关问题时调用此技能

第六章：语音与转录

6.1 TTS（文字转语音）

tts:
  provider: edge              # edge/elevenlabs/openai/xai/mistral/neutts/piper/minimax
  edge:
    voice: zh-CN-XiaoxiaoNeural
  minimax:
    model: speech-2.8-hd
    voice_id: female-tianmei
    base_url: https://api.minimax.chat/v1/t2a_v2

Provider	免费	说明
`edge`	✅	微软 Edge TTS，免费，支持中文
`neutts`	✅	本地运行，需 `neutts[all]` + `espeak-ng`
`minimax`	❌	MiniMax TTS
`elevenlabs`	❌	商业付费，音色克隆强

6.2 STT（语音转文字）

stt:
  enabled: true
  provider: local            # local（faster-whisper）/openai/mistral
  local:
    model: base              # tiny/base/small/medium/large-v3
    language: ''             # 留空则自动检测

优先级：1. 本地 faster-whisper → 2. Groq Whisper → 3. OpenAI Whisper → 4. Mistral Voxtral

6.3 语音交互

voice:
  record_key: ctrl+b         # 按键开始录音
  max_recording_seconds: 120
  auto_tts: false            # 自动 TTS 播放 AI 回复
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

第七章：Gateway 多平台网关

7.1 支持的平台

Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, Mattermost, Home Assistant, DingTalk, 飞书, 企业微信, 蓝泡泡(iMessage), 微信, API Server, Webhooks

7.2 启动方式

# 前台运行（调试用）
hermes gateway run

# 安装后台服务
hermes gateway install

# 启停服务
hermes gateway start
hermes gateway stop
hermes gateway restart

# 查看状态
hermes gateway status

7.3 WeCom 配置示例

platforms:
  wecom:
    enabled: true
    home_channel:
      platform: wecom
      chat_id: aiden
      name: Home
    extra:
      bot_id: your_bot_id
      secret: your_secret
      websocket_url: wss://openws.work.weixin.qq.com
      dm_policy: open
      group_policy: open

第八章：多 Agent 协作

8.1 delegate_task（子 Agent）

from hermes_tools import delegate_task

# 单任务
delegate_task(
    goal="调研 MiniMax TTS API 并输出报告",
    context="使用 MiniMax 平台，base_url=https://api.minimaxi.com",
    toolsets=["web", "terminal", "file"]
)

# 批量并行（最多 3 个）
delegate_task(tasks=[
    {"goal": "任务A", "context": "..."},
    {"goal": "任务B", "context": "..."},
    {"goal": "任务C", "context": "..."},
])

8.2 配置参数

delegation:
  max_concurrent_children: 5   # 最大并行子 Agent 数
  max_spawn_depth: 1          # 1=扁平（子 Agent 不能再分）
  max_iterations: 50          # 子 Agent 最大迭代数
  child_timeout_seconds: 600  # 子 Agent 超时
  subagent_auto_approve: false # 子 Agent 是否自动批准危险命令

⚠️ 子 Agent 报告"完成"不代表文件已写入磁盘。必须自行验证输出文件存在性。

第九章：故障排查

9.1 常见问题

Q: /model 斜杠命令不能用？
A: /model 不是斜杠命令，是顶层 CLI 命令。在 hermes chat 外部用 hermes model，在内部用 /model。

Q: 切换 Provider 后请求发到错误地址？
A: 跨 Provider 切换后必须清空 base_url：hermes config set model.base_url ''

Q: Cron 任务发不出消息？
A: send_message 在 Cron 会话中不可用。使用 Python 直接调用（参见 skill references/cron-send-message-workaround.md）

Q: 工具调用循环不停？
A: 检查 tool_loop_guardrails.hard_stop_enabled 是否启用

Q: OpenClaw 迁移？
A: hermes claw migrate — 从 OpenClaw 迁移设置、记忆、技能和 API Key

9.2 诊断命令

hermes doctor              # 环境诊断
hermes config check        # 配置检查
hermes logs errors        # 查看错误日志
hermes logs --since 1h    # 最近 1 小时日志
hermes debug share         # 上传调试报告
hermes dump                # 导出完整诊断信息